.. _cmsHomeGetSuccess:

cmsHomeGetSuccess 
================================
--------------------------------


SYNOPSYS
`````````````
.. code-block:: none

    VT_I4 cmsHomeGetSuccess ([in] VT_I4 BoardId, [in] VT_I4 Axis, [out] VT_PI4 IsSuccess)              

DESCRIPTION
`````````````  

- cmsHomeGetSuccess() 함수는 이 함수가 호출되기 이전에 원점복귀가 성공적으로 
  완료되었는지를 알려주는 함수입니다. 

\

- 이 함수의 사용과 호출에 있어, 제공된 ㈜커미조아의 함수 헤더 Visual Basic 에서는 함수의
  첨두어 cms 가 붙지 않습니다.


PARAMETER
`````````````

▶ BoardId: 사용자가 설정한 디바이스(보드) ID. 
 
▶ Axis : 축(채널) 번호. 축번호는 상수값으로  0번째 채널을 기준 채널로 임의의 채널을 
설정할 수 있습니다.
 
▶ IsSuccess : cmsHomeGetSuccess함수의 인자이며, 이 함수가 호출된 시점을 기준으로 이전에 
원점복귀가 성공적으로 완료된 상태인지를 알려주는 매개 변수(媒介變數)입니다.

  .. csv-table::
   :widths: 10 90
   :header-rows: 1
   :stub-columns: 0

    Value, Meaning
    "| 0 (FALSE)", "
     |               지정한 축은 현재 원점복귀가 진행 중이거나  
     |               또는 비정상적으로 완료되었습니다."
    "| 1 (TRUE)","
     |               지정한 축은 현재 원점복귀가 정상적으로 수행된 상태입니다.
     |               "    


RETURN VALUE
`````````````

+------------+-----------+
|    Value   | Meaning   |
+============+===========+
|    음수    | 수행 실패 |
+------------+-----------+
| ERR_NONE   | 수행 성공 |
+------------+-----------+

REFERENCE
`````````````

- 원점복귀의 성공 여부에 대한 플래그 값은 응용프로그램이 종료(終了)되어도 그대로  
  유지됩니다. 따라서 다시 응용프로그램이 시작되면 이전에 원점복귀를 정상적으로 
  수행했었는지를 알 수가 있습니다. 단, PC의 하드웨어적인 전원이 차단되거나 재 
  시작(Rebooting) 되면 그 값은 FALSE로 리셋됩니다. 따라서 cmsHomeGetSuccess() 함수의 
  이러한 특성(特性)을 활용하면 프로그램이 종료되었다가 다시 실행될 때 이전의 원점복귀 
  수행여부를 확인(確認)할 수가 없어서 매번 원점복귀를 수행해야 했던 불편을 보완(補完)할 
  수 있습니다. 

\

- IsSuccess 매개 변수(媒介變數)가 FALSE인 경우는 원점복귀가 진행중인 경우를 의미할 
  수도 있고 비정상적으로 종료되었음을 의미할 수도 있습니다. 따라서 cmsHomeMoveStart() 
  함수를 사용한 경우에는 먼저 cmsHomeIsBusy() 함수나 cmsHomeWaitDone() 함수를 선행하여 
  완료를 확인(確認)한 후에 cmsHomeGetSuccess()를 사용하여 성공여부를 확인(確認)하는 것이 
  정석입니다.

\

- 이전에 원점복귀가 성공적으로 수행되었더라도 해당 축의 원점복귀를 다시 시작하면 
  원점복귀의 성공 여부에 대한 플래그는 FALSE로 리셋(Reset)됩니다. 

EXAMPLE
```````````````````

- 아래의 예제에서 OnProgramInitialHome() 함수는 응용프로그램이 시작될 때 자동으로 
  원점복귀를 수행하기 위하여 호출되는 가상의 함수입니다. 단, 이때 cmsHomeGetSuccess() 
  함수를 이용하여 이전에 원점복귀가 이미 성공적으로 수행되었는지를 확인(確認)하고, 만일 
  그러한 경우라면 원점복귀를 생략하도록 합니다. 

.. code-block:: c++
 :linenos:
 :emphasize-lines: 5

    C/C++ :  
    #define DEV0 
    0 
    BOOL OnProgramInitialHome(int nAxis) 
    { 
    long dwAlreadyDone; 
    cmsHomeGetSuccess(DEV0, nAxis, &dwAlreadyDone); // 이전에 원점복귀 상태 확인(確認) 
    if(dwAlreadyDone){// 이전에 이미 원점복귀가 이루어졌으면 원점복귀 생략 
    return TRUE; 
    }
    long dwIsHomming = TRUE; 
    cmsHomeMoveStart(DEV0, nAxis, cmsDIR_N); 
    while(dwIsHomming){ 
    cmsHomeIsBusy(DEV0, nAxis, &dwIsHomming); // 원점복귀 진행여부 읽기 
    // 윈도우 메시지를 처리해준다 ( ex: PeekMessage) 
    } 
    // 원점복귀의 성공여부를 확인(確認)하여 처리한다. // 
    long dwIsSuccess; 
    cmsHomeGetSuccess(DEV0, nAxis, &dwIsSuccess); 
    if(dwIsSuccess){ 
    MessageBox(NULL, “원점복귀를 성공적으로 수행하였습니다.”, “Message”, MB_OK); 
    }else{ 
    char szErrMsg[CMS_MAX_STR_LEN_ERR]; 
    char szErrReason[CMS_MAX_STR_LEN_ERR]; 
    long dwErrCode; 
    cmsErrGetLastCode(DEV0, nAxis, &dwErrCode); 
    cmsErrGetString(DEV0, dwErrCode, szErrReason, CMS_MAX_STR_LEN_ERR); 
    sprintf(szErrMsg, “다음과 같은 이유로 원점복귀에 실패하였습니다.\n%s”, szErrReason); 
    MessageBox(NULL, szErrMsg, “Motion Error”, MB_OK | MB_ICONERROR); 
    } 
    } 

    -------------------------------------------------------------------------------------------

    Visual Basic 
    Const DEV0 = 0 
    Dim dwIsHomming As Long 
    Dim dwIsSuccess As Long 
    dwIsHomming = True 
    Call HomeMoveStart(DEV0, 0, cmsDIR_N) 
    Do While (dwIsHomming) 
    '원점 진행여부 확인(確認) 
    Call HomeIsBusy(DEV0, 0, dwIsHomming)  
    Loop 
    If (HomeGetSuccess(DEV0, 0, dwIsSuccess) <> ERR_NONE)  
    Then 
    // 에러메시지 출력 
    If (dwIsSuccess) Then 
    MsgBox ("원점 복귀를 성공적으로 수행하였습니다.") 
    End If 

    -------------------------------------------------------------------------------------------